docs: Add more information to gtk_widget_set_realized()

It's important to point out that widgets should only be marked as
realized very late in the process. Even GTK widgets don't get this
right.

https://bugzilla.gnome.org/show_bug.cgi?id=726717

diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 9541e596e212d5bb61361a14f88d1b9a9ebc065d..b82819a852af64b2926e95d99d7c8068f865bfcc 100644 (file)
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -8609,7 +8609,9 @@ gtk_widget_get_realized (GtkWidget *widget)
  * @widget: a #GtkWidget
  * @realized: %TRUE to mark the widget as realized
  *
- * Marks the widget as being realized.
+ * Marks the widget as being realized. This function must only be 
+ * called after all #GdkWindows for the @widget have been created 
+ * and registered.
  *
  * This function should only ever be called in a derived widget's
  * “realize” or “unrealize” implementation.